home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / graphics / mfpic / mfpic / mfpicdoc.tex < prev    next >
Text File  |  1993-10-25  |  33KB  |  987 lines
  1. %%%
  2. %%%  File: mfpicdoc.tex
  3. %%%  Version:  0.25
  4. %%%  Date:  Tue 26 Oct 1993
  5. %%%
  6. %%%  Principal Author - Thomas E. Leathrum
  7. %%%  Assistant        - Geoffrey Tobin
  8. %%%
  9.  
  10. \magnification=\magstep1
  11.  
  12. % heading macros
  13. \newskip\myskip\myskip=5pt plus 1pt
  14. \def\head#1{\vskip\myskip \noindent $\bullet$ {\it #1}
  15. \par\nobreak}
  16. \def\subhead#1{\vskip\myskip {\sl #1} \par\nobreak}
  17.  
  18. % abbreviations
  19. \def\LaTeX{%
  20. {\rm L\raise.42ex\hbox{\kern-.3em a}\kern-.15em\TeX}}
  21. \def\PiCTeX{%
  22. {\rm
  23. P\kern-.12em\lower.5ex\hbox{I}\kern-.075emC%
  24. \kern-.11em\TeX}}
  25. \font\manual=logo10 % may want to use manfnt here instead
  26. \def\MF{{\manual META}\-{\manual FONT}}
  27. \def\PS{{\rm Post}\-{\rm Script}}
  28.  
  29. % metacode macros
  30. \def\<{$\langle$\bgroup\it}\def\>{\egroup$\rangle$}
  31. % macro to typeset macros
  32. % e.g. \macro{name}[?arg1][arg2] gives
  33. % \name[arg1]{arg2}
  34. \def\gobble#1{}
  35. \def\dooptparam[#1]{{\tt[#1]}\futurelet\nchr\domacro}
  36. \def\dofixparam[#1]{{\tt\string{#1\string}}%
  37. \futurelet\nchr\domacro}
  38. \def\doparamswap{\if?\nchr%
  39. \dooptparam[\expandafter\gobble\else\dofixparam[\fi}
  40. \def\doparam{\futurelet\nchr\doparamswap}
  41. \def\ddoparam{\expandafter\doparam\gobble}
  42. \def\domacro{\if[\nchr\expandafter\ddoparam\fi}
  43. \def\macro#1{{\tt\char\escapechar#1}%
  44. \futurelet\nchr\domacro}
  45.  
  46. \centerline{\bf mfpic --- Pictures in \TeX\ with Metafont --- version 0.25}
  47.  
  48. \head{Why?}
  49.  
  50. I got the idea for {\tt mfpic} mostly out of a feeling of
  51. frustration.  Different output mechanisms for printing or
  52. viewing \TeX\ DVI files each have their own ways to
  53. include pictures.  More often than not, there are
  54. provisions for including \PS\ data into a DVI file using
  55. \TeX\ \macro{special}'s.  However, this technique seems
  56. far from \TeX's ideal of device-independence, and
  57. besides, different \TeX\ output drivers handle these
  58. \macro{special}'s in different ways.  The same problems
  59. arise with including {\tt tpic} \macro{special}'s.
  60. \LaTeX's {\tt picture} environment has a hopelessly
  61. limited supply of available objects to draw --- if you
  62. want to draw a graph of a polynomial curve, you're out of
  63. luck.  There is, of course, \PiCTeX, which is wonderfully
  64. flexible and general, but its most obvious feature is its
  65. speed --- or rather lack of it.  Processing a single
  66. picture in \PiCTeX\ can often take several minutes.  It
  67. occured to me that it might be possible to take advantage
  68. of the fact that \MF\ is {\it designed} for drawing
  69. things.  The result of pursuing this idea is {\tt mfpic},
  70. a set of macros for \TeX\ and \MF\ which incorporate
  71. Metafont-drawn pictures into a \TeX\ file.  The nature of
  72. the macros, from the user's point of view, is very much
  73. like \PiCTeX.  I do not pretend that {\tt mfpic} has
  74. anything like the scope of \PiCTeX, but it should suit
  75. most purposes for drawing small graphs and including them
  76. in your \TeX\ documents.
  77.  
  78. \head{Author.}
  79.  
  80. {\tt mfpic} was written primarily by Tom Leathrum
  81. (formerly moth@dartmouth.edu) during the late spring and summer of
  82. 1992.  Those who helped most in this process are credited
  83. in the Acknowledgements.
  84.  
  85. \head{Manifest.}
  86.  
  87. Seven files are included in the {\tt mfpic} distribution:\hfil\break
  88. \hbox{}\kern 1cm   {\tt mfpicdoc.tex} (this document, which can be processed
  89. in plain \TeX),\hfil\break
  90. \hbox{}\kern 1cm    {\tt mfpic.tex} (the \TeX\ macros),\hfil\break
  91. \hbox{}\kern 1cm    {\tt graphbase.mf} (the \MF\ macros),\hfil\break
  92. \hbox{}\kern 1cm    {\tt objects.tex} (a sample file containing at least one
  93. picture of each object),\hfil\break
  94. \hbox{}\kern 1cm    {\tt pictures.tex} (a short sample file with a few more
  95. complicated pictures),\hfil\break
  96. \hbox{}\kern 1cm    {\tt lamfpic.tex} (an outmoded short header file
  97. for LaTeX, which now merely inputs mfpic.tex, and remains solely for
  98. backward compatibility), and\hfil\break
  99. \hbox{}\kern 1cm    {\tt lapictures.tex} (the \LaTeX\ version of
  100. {\tt pictures.tex}).\hfil\break
  101. Information on how to set up a few specific configurations of
  102. computers is also available, separately.
  103.  
  104. \head{Setting Up and Processing.}
  105.  
  106. Setting up \TeX\ and \MF\ to process these files will, to
  107. an extent, depend on your local installation.  The
  108. biggest problem you are likely to have, regardless of
  109. your installation, will be convincing \TeX\ and its
  110. output drivers to find \MF's output files.
  111.  
  112. To process the sample file, first run \TeX\ on the file
  113. {\tt pictures.tex}.  \TeX\ will complain that it can't
  114. find the file {\tt pics.tfm}, but will continue
  115. processing the file anyway.  When the file is finished
  116. processing, you will now have a file called
  117. {\tt pics.mf}.  This is the \MF\ file containing the
  118. descriptions of the pictures for {\tt pictures.tex}.  You
  119. need to run \MF\ on {\tt pics.mf}, with
  120. \macro{mode=localfont} set up.  (Read your \MF\ manual to
  121. see how to do this.) Now that you have the font and font
  122. metric files generated by \MF, reprocess the file
  123. {\tt pictures.tex} with \TeX.  The resulting DVI file
  124. should now be complete, and you should be able to print
  125. and view it at your computer (assuming your viewer and
  126. print driver have been set up to be able to find the font
  127. generated by {\tt pics.mf}).
  128.  
  129. These three steps of processing --- processing with \TeX,
  130. processing with \MF, and reprocessing with \TeX\ --- may
  131. not always be necessary.  In particular, if you change
  132. the TeX document without making any changes at all to the
  133. pictures, then there will be no need to repeat either of
  134. the last two steps.  There is also a somewhat subtle
  135. circumstance under which you can skip the third step ---
  136. if you change the picture in such a way as {\it not} to
  137. affect the font metric file, then you do not have to
  138. reprocess with \TeX, because the original metric used for
  139. the first step will put the pictures in the right places.
  140. The only {\tt mfpic} macros that affect the font metric
  141. file are the two macros listed in the {\sl Files and
  142. Environments} section below.
  143.  
  144. \head{How It Works.}
  145.  
  146. When you run \TeX\ on the file {\tt pictures.tex}, \TeX\
  147. generates a file {\tt pics.mf}.  This file is formed by
  148. \macro{write} commands in the {\tt mfpic} macros.  The
  149. user should never have to read or change the file {\tt
  150. pics.mf} directly --- the {\tt mfpic} macros take care of
  151. it.  The user familiar with \MF\ will notice, by looking
  152. at the {\tt mfpic} macros, that the {\tt mfpic} drawing
  153. macros translate almost directly into simple \MF\ {\tt
  154. draw} commands.  The \macro{mflabel}'s and
  155. \macro{mfcaption}'s, however, are placed on the graph by
  156. \TeX, not \MF.
  157.  
  158. \head{The Macros.}
  159.  
  160. \subhead{Files and Environments.}
  161.  
  162. \vskip\myskip
  163. \noindent\macro{opengraphsfile}[\<font\>]$\dots$
  164. \macro{closegraphsfile}
  165.  
  166. \nobreak
  167. These macros open and close the Metafont file
  168. which will contain the pictures to be included in this
  169. document.  The name of the file will be {\tt\<font\>.mf}.
  170. If the \<font\> parameter is changed, you will have to
  171. reprocess the \TeX\ file after processing
  172. {\tt\<font\>.mf}.
  173.  
  174.  
  175. \vskip\myskip
  176. \noindent\macro{mfpicture}[?\<xscale\>][?\<yscale\>]%
  177. [\<xneg\>][\<xpos\>][\<yneg\>][\<ypos\>]
  178. $\dots$\macro{endmfpicture}
  179.  
  180. \nobreak
  181. These macros open and close the environment in which the rest of the
  182. macros below make sense.
  183. The \macro{mfpicture} macro also sets up the local coordinate system
  184. for the picture.
  185. The \<xscale\> and \<yscale\> parameters establish the length of the
  186. coordinate system units, as multiples of the user-settable dimension
  187. \macro{mfpicunit} which is initially one \TeX\ point ({\tt 1pt}).
  188. At least one scale parameter must be specified, but if only one is
  189. specified, then they are assumed to be equal.
  190. The \<xneg\> and \<xpos\> parameters establish the lower and upper
  191. (resp.) bounds for the $x$-axis coordinates;
  192. similarly, \<yneg\> and \<ypos\> establish the bounds for the
  193. $y$-axis.
  194. These bounds are expressed in local units --- in other words,
  195. the actual width of the picture will be
  196. \<xscale\>$\cdot$(\<xpos\>$-$\<xneg\>) points.
  197. These scales and bounds are used primarily to establish the metric for
  198. the character containing the picture described within the environment.
  199. If any of these parameters are changed, the {\tt\<font\>.tfm} file
  200. will be affected, so you will have to reprocess the \TeX\ file after
  201. processing {\tt\<font\>.mf}.
  202.  
  203. \vskip\myskip
  204. The rest of the {\tt mfpic}  macros do not
  205. affect the font metric file ({\tt\<font\>.tfm}), and so
  206. if these commands are changed or added in your document,
  207. you will not have to repeat the third step of processing
  208. (reprocessing with \TeX) to complete your \TeX\ document.
  209.  
  210. \vskip\myskip
  211. For backward compatibility with version {\tt 0.2} of {\tt mfpic}, if
  212. \macro{picture} is {\it not} already defined, then it is let equal to
  213. \macro{mfpicture}, and \macro{endpicture} is let equal to
  214. \macro{endmfpicture}.
  215. Also, the macros \macro{mfpic} and \macro{endmfpic} are provided as
  216. abbreviations for \macro{mfpicture} and \macro{endmfpicture},
  217. respectively.
  218.  
  219. \vskip\myskip
  220. For the remainder of the macros, the numerical parameters
  221. are expressed in the units of the local coordinate system
  222. specified by \macro{mfpicture}, unless otherwise indicated.
  223.  
  224. \subhead{Points, Lines, Arrows, and Dotted Lines.}
  225.  
  226. \vskip\myskip
  227. \noindent\macro{point}[(\<xval\>,\<yval\>)]
  228.  
  229. \nobreak
  230. This macro draws a small filled circle centered
  231. at the point {\tt (\<xval\>,\<yval\>)}.  The diameter of
  232. the circle is determined by the dimension
  233. \macro{pointsize}.  The default value of
  234. \macro{pointsize} is 2 points.
  235.  
  236. \vskip\myskip
  237. \noindent\macro{line}[(\<xval0\>,\<yval0\>),%
  238. (\<xval1\>,\<yval1\>)]
  239.  
  240. \nobreak
  241. This macro draws the line segment
  242. with endpoints at the points
  243. {\tt (\<xval0\>,\<yval0\>)} and
  244. {\tt (\<xval1\>,\<yval1\>)}.
  245.  
  246. \vskip\myskip
  247. \noindent\macro{arrow}[(\<xval0\>,\<yval0\>),%
  248. (\<xval1\>,\<yval1\>)]
  249.  
  250. \nobreak
  251. This macro draws an arrow starting from the point
  252. {\tt (\<xval0\>,\<yval0\>)}
  253. and pointing to the point {\tt (\<xval1\>,\<yval1\>)}.
  254. The length of the arrowhead is determined by the
  255. dimension \macro{headlen}.  The default value of
  256. \macro{headlen} is 3 points.
  257. Each side of the arrowhead is a  \MF\ Bezier curve
  258. starting from the tip of the arrowhead and heading
  259. initially parallel to the arrow line, then bending out to
  260. the endpoint.
  261.  
  262. \vskip\myskip
  263. \noindent\macro{dottedline}[(\<xval0\>,\<yval0\>),%
  264. (\<xval1\>,\<yval1\>)]
  265.  
  266. \nobreak
  267. This macro draws the dotted (or, more properly, dashed)
  268. line segment  specified as in the \macro{line} macro.
  269. The length of the dashes is determined
  270. by the dimension \macro{dashlen}.  The default value of
  271. \macro{dashlen} is 4 points.   The space between the
  272. dashes is determined by the dimension \macro{dashspace}.
  273. The default value of \macro{dashspace} is  4 points.  The
  274. space between the dashes may be adjusted by as much as
  275. ${dashspace}\over{n}$, where $n$ is the number of spaces
  276. appearing in the line segment, in order not to have
  277. partial dashes at the ends.
  278.  
  279. \vskip\myskip
  280. \noindent\macro{dottedarrow}[(\<xval0\>,\<yval0\>),%
  281. (\<xval1\>,\<yval1\>)]
  282.  
  283. \nobreak
  284. This macro draws a dotted arrow specified as in the
  285. \macro{arrow} macro, with the
  286. arrowhead the same
  287. shape and size as in the \macro{arrow} command and the
  288. dash length and spacing
  289. determined as in the \macro{dottedline} macro.
  290.  
  291. \subhead{Axes and Axis Marks.}
  292.  
  293. \vskip\myskip
  294. \noindent\macro{axes}
  295.  
  296. \nobreak
  297. This macro draws the $x$ and $y$ axes for the coordinate
  298. system.  The length of the
  299. arrowhead is determined by the
  300. dimension \macro{axisheadlen}.  The default value of
  301. \macro{axisheadlen} is 5 points.
  302. The shape of the arrowhead is determined as in the
  303. {\tt\string\arrow} macro.
  304.  
  305. \vskip\myskip
  306. \noindent\macro{xmarks}[\<value0\>,\<value1\>,$\dots$]
  307. and
  308. \macro{ymarks}[\<value0\>,\<value1\>,$\dots$]
  309.  
  310. \nobreak
  311. These macros place hash (tic) marks on the $x$ and $y$ axes
  312. (resp.) at the places indicated by the values in the list.
  313. The length of the hash marks is determined by the dimension
  314. \macro{hashlen}.  The default value of \macro{hashlen} is 4 points.
  315.  
  316. \subhead{Polygons.}
  317.  
  318. \vskip\myskip
  319. \noindent\macro{rect}[(\<xval0\>,\<yval0\>),%
  320. (\<xval1\>,\<yval1\>)]
  321.  
  322. \nobreak
  323. This macro draws  the rectangle  specified by the
  324. given points {\tt (\<xval0\>,\<yval0\>)} and
  325. {\tt (\<xval1\>,\<yval1\>)} being any two
  326. opposite corners of the rectangle.
  327.  
  328. \vskip\myskip
  329. \noindent\macro{dottedrect}[(\<xval0\>,\<yval0\>),%
  330. (\<xval1\>,\<yval1\>)]
  331.  
  332. \nobreak
  333. This macro draws  the dotted line rectangle
  334. specified as in the \macro{rect} macro.
  335. The dash length and spacing are
  336. determined as in the \macro{dottedline} macro.
  337.  
  338. \vskip\myskip
  339. \noindent\macro{block}[(\<xval0\>,\<yval0\>),%
  340. (\<xval1\>,\<yval1\>)]
  341.  
  342. \nobreak
  343. This macro draws  the filled rectangle
  344. specified as in the \macro{rect} macro.
  345.  
  346. \vskip\myskip
  347. \noindent\macro{rectshade}[(\<xval0\>,\<yval0\>),%
  348. (\<xval1\>,\<yval1\>)]
  349.  
  350. \nobreak
  351. This macro draws dots shading in the rectangle
  352. specified as in the \macro{rect} macro.
  353. This macro does {\it not} draw the
  354. outline rectangle.  The spacing between the dots is
  355. determined by the
  356. dimension \macro{shadespace}.  The default value of
  357. \macro{shadespace} is  1 point.
  358.  
  359. \vskip\myskip
  360. \noindent\macro{polygon}[(\<xval0\>,\<yval0\>),%
  361. (\<xval1\>,\<yval1\>),$\dots$]
  362.  
  363. \nobreak
  364. This macro draws a polygon with the specified points
  365. at the vertices.  The resulting
  366. polygon can {\it not} be allowed to cross itself.
  367.  
  368. \vskip\myskip
  369. \noindent\macro{polyshade}[(\<xval0\>,\<yval0\>),%
  370. (\<xval1\>,\<yval1\>),$\dots$]
  371.  
  372. \nobreak
  373. This macro shades the region enclosed by the polygon specified as in the
  374. \macro{polygon} macro.  The spacing between dots is determined as in the
  375. \macro{shaderect} macro.
  376.  
  377. \vskip\myskip
  378. \noindent\macro{polyfill}[(\<xval0\>,\<yval0\>),%
  379. (\<xval1\>,\<yval1\>),$\dots$]
  380.  
  381. \nobreak
  382. This macro fills the region enclosed by the polygon
  383. specified as in the \macro{polygon} macro.
  384.  
  385. \subhead{Parameters.}
  386.  
  387. There are many parameters to {\tt mfpic} which the user
  388. can modify to obtain different effects, such as different
  389. arrowhead size or shape.  Most of these parameters have
  390. been described already in the context of macros they
  391. modify, but they are all described together here.  Most
  392. of the parameters are stored by \TeX\ as dimensions, and
  393. so are available globally, even if there is no \MF\ file
  394. open; changes to them are subject to the usual \TeX\
  395. rules of scope.  Some parameters, however, are stored by
  396. \MF, so the macros to change them will have no effect
  397. unless a \MF\ file is open, and the changes are subject
  398. to \MF's rules of scope --- to the {\tt mfpic} user, this
  399. means that changes inside the \macro{mfpicture} $\dots$
  400. \macro{endmfpicture} environment are local to that
  401. environment, but other \TeX\ groupings have no effect on
  402. scope.
  403.  
  404. \vskip\myskip
  405. \noindent\macro{pointsize}
  406.  
  407. \nobreak
  408. This dimension stores the diameter of the filled circle
  409. drawn by the \macro{point}
  410. macro.  The default value is 2 points.
  411.  
  412. \vskip\myskip
  413. \noindent\macro{pen}[\<pensize\>]
  414.  
  415. \nobreak
  416. This macro establishes the width of the drawing pen.
  417. The default is 0.5 points.
  418. This quantity is stored by \MF.
  419.  
  420. \vskip\myskip
  421. \noindent\macro{headlen}
  422.  
  423. \nobreak
  424. This dimension stores the length of the arrowhead
  425. drawn by the \macro{arrow} macro.
  426. The default value is 3 points.
  427.  
  428. \vskip\myskip
  429. \noindent\macro{headshape}[\<hdwdr\>][\<hdten\>]
  430.  
  431. \nobreak
  432. This macro establishes the shape of the arrowhead drawn
  433. by the \macro{arrow} and \macro{axes} macros.  The value
  434. of \<hdwdr\> is the ratio of the width of the arrowhead
  435. to its length, and \<hdten\> is the tension of the Bezier
  436. curves.  The default values are both 1.  These values are
  437. stored by \MF.  Setting  \macro{headshape}[1][infinity]
  438. will make the sides of the arrowheads straight lines.
  439.  
  440. \vskip\myskip
  441. \noindent\macro{dashlen}, \macro{dashspace}
  442.  
  443. \nobreak
  444. These dimensions store, respectively, the length of
  445. dashes and the length of spaces between dashes for lines
  446. drawn by the \macro{dottedline} macro.  The space between
  447. the dashes may be adjusted by as much as
  448. ${dashspace}\over{n}$, where $n$ is the number of spaces
  449. appearing in the line segment, in order not to have
  450. partial dashes at the ends.  The default values are both
  451. 4 points.
  452.  
  453. \vskip\myskip
  454. \noindent\macro{dashlineset}, \macro{dotlineset}
  455.  
  456. \nobreak
  457. These macros provide convenient standard settings for the
  458. \macro{dashlen} and \macro{dashspace} dimensions.  The
  459. macro \macro{dashlineset} sets both values to 4 points;
  460. the macro \macro{dotlineset} sets \macro{dashlen} to 1
  461. point and \macro{dashspace} to 2 points.
  462.  
  463. \vskip\myskip
  464. \noindent\macro{axisheadlen}
  465.  
  466. \nobreak
  467. This dimension stores the length of the arrowhead
  468. drawn by the \macro{axes} macro.
  469. The default value is 5 points.
  470.  
  471. \vskip\myskip
  472. \noindent\macro{hashlen}
  473.  
  474. \nobreak
  475. This dimension stores the length of the axis
  476. hash (tic) marks drawn by the \macro{xmarks}
  477. and \macro{ymarks} macros.  The default value is 4 points.
  478.  
  479. \vskip\myskip
  480. \noindent\macro{shadespace}
  481.  
  482. \nobreak
  483. This dimension establishes the spacing between dots
  484. drawn by the \macro{rectshade} and other shading
  485. macros.  The default value is 1 point.
  486.  
  487. \vskip\myskip
  488. \noindent\macro{darkershade}, \macro{lightershade}
  489.  
  490. \nobreak
  491. These macros both multiply the \macro{shadespace}
  492. dimension by constant factors,
  493. $5\over6$ and $6\over5$ respectively, to provide
  494. convenient standard settings for
  495. several levels of shading.
  496.  
  497. \subhead{Circles, Ellipses, and Disks.}
  498.  
  499. \vskip\myskip
  500. \noindent\macro{circle}[(\<xval\>,\<yval\>),\<rad\>]
  501.  
  502. \nobreak
  503. This macro draws a circle centered at the
  504. point {\tt (\<xval\>,\<yval\>)} and with radius \<rad\>.
  505.  
  506. \vskip\myskip
  507. \noindent\macro{circshade}[(\<xval\>,\<yval\>),\<rad\>]
  508.  
  509. \nobreak
  510.  
  511. This macro draws a shaded circle, determined as in the
  512. \macro{circle} macro.  The spacing between dots is
  513. determined as in the \macro{shaderect} macro.
  514.  
  515. \vskip\myskip
  516. \noindent\macro{cdisk}[(\<xval\>,\<yval\>),\<rad\>]
  517.  
  518. \nobreak
  519. This macro draws a filled circle, determined as in the
  520. \macro{circle} macro.
  521.  
  522. \vskip\myskip
  523. \noindent\macro{ellipse}[(\<xval\>,\<yval\>),%
  524. \<xrad\>,\<yrad\>]
  525.  
  526. \nobreak
  527. This macro draws an ellipse with the $x$ radius \<xrad\>
  528. and $y$ radius \<yrad\>, centered at  the point {\tt
  529. (\<xval\>,\<yval\>)}.
  530.  
  531. \vskip\myskip
  532. \noindent\macro{ellshade}[(\<xval\>,\<yval\>),%
  533. \<xrad\>,\<yrad\>]
  534.  
  535. \nobreak
  536. This macro draws a shaded ellipse, determined as in the
  537. \macro{ellipse} macro.  The spacing between dots is
  538. determined as in the \macro{shaderect} macro.
  539.  
  540. \vskip\myskip
  541. \noindent\macro{edisk}[(\<xval\>,\<yval\>),%
  542. \<xrad\>,\<yrad\>]
  543.  
  544. \nobreak
  545. This macro draws a filled ellipse, determined as in the
  546. \macro{ellipse} macro.
  547.  
  548. \vskip\myskip
  549. \noindent\macro{rotatedellipse}[(\<xval\>,\<yval\>),%
  550. \<xrad\>,\<yrad\>,\<theta\>]
  551.  
  552. \nobreak
  553. This macro draws an ellipse with the $x$ radius \<xrad\>
  554. and $y$ radius \<yrad\> (before rotation), centered at
  555. the point {\tt (\<xval\>,\<yval\>)}, and rotated around
  556. its center by the angle \<theta\> (expressed in degrees).
  557.  
  558. \vskip\myskip
  559. \noindent\macro{rotatedellshade}[(\<xval\>,\<yval\>),%
  560. \<xrad\>,\<yrad\>,\<theta\>]
  561.  
  562. \nobreak
  563. This macro draws a shaded ellipse, determined as in the
  564. \macro{rotatedellipse} macro.  The spacing between dots
  565. is determined as in the \macro{shaderect} macro.
  566.  
  567. \vskip\myskip
  568. \noindent\macro{rotatededisk}[(\<xval\>,\<yval\>),%
  569. \<xrad\>,\<yrad\>,\<theta\>]
  570.  
  571. \nobreak
  572. This macro draws a filled ellipse, determined as in the
  573. \macro{rotatedellipse} macro.
  574.  
  575. \subhead{Circular Arcs.}
  576.  
  577. \vskip\myskip
  578. \noindent\macro{arc}[(\<xval0\>,\<yval0\>),%
  579. (\<xval1\>,\<yval1\>),\<sweep\>]
  580.  
  581. \nobreak
  582. This macro draws a circular arc starting from the point
  583. {\tt (\<xval0\>,\<yval0\>)}, ending at the point
  584. {\tt (\<xval1\>,\<yval1\>)}, and covering an arc angle of
  585. \<sweep\> degrees, measured counterclockwise around the
  586. center of the circle.  If, for example, the points {\tt
  587. (\<xval0\>,\<yval0\>)} and {\tt (\<xval1\>,\<yval1\>)}
  588. lie on a horizontal line with {\tt (\<xval0\>,\<yval0\>)}
  589. to the left, and \<sweep\> is between 0 and 180
  590. (degrees), then the center of the circle will be above
  591. the horizontal line (in order for the angle to be
  592. counterclockwise).  Negative values of \<sweep\> give
  593. arcs curving in the other direction.
  594.  
  595. \vskip\myskip
  596. \noindent\macro{arcarrow}[(\<xval0\>,\<yval0\>),%
  597. (\<xval1\>,\<yval1\>),\<sweep\>]
  598.  
  599. \nobreak
  600.  
  601. This marco draws an arc, specified as in the \macro{arc}
  602. macro, with an arrowhead placed at the
  603. {\tt (\<xval1\>,\<yval1\>)} end.
  604. The shape and size of the
  605. arrowhead are the same as in the \macro{arrow} macro.
  606.  
  607. \vskip\myskip
  608. \noindent\macro{arcshade}[(\<xval0\>,\<yval0\>),%
  609. (\<xval1\>,\<yval1\>),\<sweep\>]
  610.  
  611. \nobreak
  612.  
  613. This macro shades the region enclosed by the arc,
  614. specified as in the \macro{arc} macro, and the line
  615. segment between {\tt (\<xval0\>,\<yval0\>)} and
  616. {\tt (\<xval1\>,\<yval1\>)}.  The spacing between dots is
  617. determined as in the \macro{shaderect} macro.
  618.  
  619. \vskip\myskip
  620. \noindent\macro{arcfill}[(\<xval0\>,\<yval0\>),%
  621. (\<xval1\>,\<yval1\>),\<sweep\>]
  622.  
  623. \nobreak
  624. This macro fills the region specified as in the
  625. \macro{arcshade} macro.
  626.  
  627. \subhead{Polar Coordinates.}
  628.  
  629. \vskip\myskip
  630. \noindent\macro{linedir}[(\<xval\>,\<yval\>),%
  631. \<theta\>,\<length\>]
  632.  
  633. \nobreak
  634. This macro draws a line segment starting from the point
  635. {\tt (\<xval\>,\<yval\>)} and going in the direction
  636. specified by \<theta\>, where \<theta\> is an angle
  637. measured in degrees counterclockwise from the direction
  638. parallel to the positive $x$ axis, and with length
  639. \<length\>.
  640.  
  641. \vskip\myskip
  642. \noindent\macro{arrowdir}[(\<xval\>,\<yval\>),%
  643. \<theta\>,\<length\>]
  644.  
  645. \nobreak
  646. This macro draws an arrow starting from the point
  647. {\tt (\<xval\>,\<yval\>)} and going in the
  648. direction specified
  649. by \<theta\>, where \<theta\> is an angle measured in
  650. degrees counterclockwise from the direction parallel to
  651. the positive $x$ axis, with length \<length\>, and with
  652. an arrowhead at the end opposite the point {\tt
  653. (\<xval\>,\<yval\>)}.  The size and shape of the
  654. arrowhead are determined as in the \macro{arrow} macro.
  655.  
  656. \vskip\myskip
  657. \noindent\macro{arcth}[(\<xval\>,\<yval\>),%
  658. \<theta1\>,\<theta2\>,\<rad\>]
  659.  
  660. \nobreak
  661. This macro draws the arc with center at the point
  662. {\tt (\<xval\>,\<yval\>)}, of radius \<rad\>,
  663. from the angle
  664. \<theta1\> to the angle \<theta2\>, where both angles are
  665. measured in degrees counterclockwise from the direction
  666. parallel to the $x$ axis.
  667.  
  668. \vskip\myskip
  669. \noindent\macro{arctharrow}[(\<xval\>,\<yval\>),%
  670. \<theta1\>,\<theta2\>,\<rad\>]
  671.  
  672. \nobreak
  673. This macro draws an arc arrow, with the arc specified as
  674. in the \macro{arcth} macro.
  675.  
  676. \vskip\myskip
  677. \noindent\macro{wedgeshade}[(\<xval\>,\<yval\>),%
  678. \<theta1\>,\<theta2\>,\<rad\>]
  679.  
  680. \nobreak
  681. This macro shades the wedge-shaped region, from
  682. the angle \<theta1\> to the angle \<theta2\> inside the
  683. circle with center at the point {\tt (\<xval\>,\<yval\>)}
  684. and radius \<rad\>, where both angles are measured in
  685. degrees counterclockwise from the direction parallel to
  686. the $x$ axis.  The spacing between dots is determined as
  687. in the \macro{shaderect} macro.
  688.  
  689. \vskip\myskip
  690. \noindent\macro{wedgefill}[(\<xval\>,\<yval\>),%
  691. \<theta1\>,\<theta2\>,\<rad\>]
  692.  
  693. \nobreak
  694. This macro fills the wedge-shaped region specified
  695. as in the \macro{wedgeshade} macro.
  696.  
  697. \subhead{Curves.}
  698.  
  699. \vskip\myskip
  700. \noindent\macro{curve}[(\<xval0\>,\<yval0\>),%
  701. (\<xval1\>,\<yval1\>),$\dots$]
  702.  
  703. \nobreak
  704. This macro draws a \MF\ Bezier path through the points
  705. specified, in the order specified.
  706.  
  707. \vskip\myskip
  708. \noindent\macro{polyline}[(\<xval0\>,\<yval0\>),%
  709. (\<xval1\>,\<yval1\>),$\dots$]
  710.  
  711. \nobreak
  712. This macro draws a piecewise linear path through the points
  713. specified, in the order specified.
  714. For backward compatibility with version {\tt 0.2},
  715. \macro{polycurve} is let equal to \macro{polyline},
  716. but {\tt polyline} is recommended as a more descriptive name.
  717.  
  718. \vskip\myskip
  719. \noindent\macro{curvedarrow}[(\<xval0\>,\<yval0\>),%
  720. (\<xval1\>,\<yval1\>),$\dots$]
  721.  
  722. \nobreak
  723. This macro draws a \MF\ Bezier curve, specified as in the
  724. \macro{curve} macro, then puts an arrowhead at the end.
  725. The arrowhead is the same size and shape as the arrowhead
  726. in the \macro{arrow} macro.
  727.  
  728. \vskip\myskip
  729. \noindent\macro{polyarrow}[(\<xval0\>,\<yval0\>),%
  730. (\<xval1\>,\<yval1\>),$\dots$]
  731.  
  732. \nobreak
  733. This macro draws a polygonal path, specified as in the
  734. \macro{polycurve} macro, then puts an arrowhead at the
  735. end.  The arrowhead is the same size and shape as the
  736. arrowhead in the \macro{arrow} macro.
  737.  
  738. \subhead{Cyclic Curves.}
  739.  
  740. \vskip\myskip
  741. \noindent\macro{cyclic}[(\<xval0\>,\<yval0\>),%
  742. (\<xval1\>,\<yval1\>),$\dots$]
  743.  
  744. \nobreak
  745. This macro draws a cyclic \MF\ Bezier curve through the
  746. points specified.  The curve can {\it not} be allowed to
  747. cross itself.
  748.  
  749. \vskip\myskip
  750. \noindent\macro{cycleshade}[(\<xval0\>,\<yval0\>),%
  751. (\<xval1\>,\<yval1\>),$\dots$]
  752.  
  753. \nobreak
  754. This macro shades the region enclosed by the cyclic curve
  755. specified as in the \macro{cyclic} macro.  The spacing
  756. between dots is determined as in the \macro{shaderect}
  757. macro.
  758.  
  759. \vskip\myskip
  760. \noindent\macro{cyclefill}[(\<xval0\>,\<yval0\>),%
  761. (\<xval1\>,\<yval1\>),$\dots$]
  762.  
  763. \nobreak
  764. This macro fills the region enclosed by the cyclic curve
  765. specified as in the \macro{cyclic} macro.
  766.  
  767. \subhead{Functions.}
  768.  
  769. \vskip\myskip
  770. \noindent\macro{function}[\<xmin\>,\<xmax\>,%
  771. \<step\>,\<expr\>]
  772.  
  773. \nobreak
  774.  
  775. This macro plots the function determined by
  776. $f(x)=$\<expr\>, where \<expr\> is written with the only
  777. unknown being {\tt x}, using as $x$ values the points
  778. starting with \<xmin\> and stepping by \<step\> until
  779. reaching \<xmax\>.  The function is interpolated with a
  780. \MF\ Bezier path.  The expression {\it expr} is passed
  781. directly into the corresponding \MF\ macro and
  782. interpreted there, so \MF's rules for algebraic
  783. expressions apply.  Operations available include {\tt +},
  784. {\tt -}, {\tt *}, {\tt /}, and {\tt **}
  785. ({\tt x**y}$=x^y$), with {\tt(} and {\tt )} for grouping.
  786. Functions available include {\tt round}, {\tt floor},
  787. {\tt ceiling}, {\tt abs}, {\tt sqrt}, {\tt sind},
  788. {\tt cosd}, {\tt mlog}, and {\tt mexp}.  ({\it Notes:}
  789. the trigonometric functions {\tt sind} and {\tt cosd}
  790. take arguments in degrees; {\tt mlog(x)}$=256\ln x$, and
  791. {\tt mexp} is its inverse.  There are other operations
  792. and functions available, but these are the most useful
  793. for plotting purposes.) You can also define the function
  794. $f(x)$ by cases using the Metafont conditional expression
  795. {\tt if \<boolean\>: \<expr\> else: \<expr\> fi}.
  796. Relations available for the \<boolean\> part of the
  797. expression include {\tt =}, {\tt <}, {\tt >}, {\tt <=},
  798. and {\tt >=}.
  799.  
  800. \vskip\myskip
  801. \noindent\macro{polyfunction}[\<xmin\>,\<xmax\>,%
  802. \<step\>,\<expr\>]
  803.  
  804. \nobreak
  805. This macro plots the function determined by
  806. $f(x)=$\<expr\>, as in the \noindent\macro{function}
  807. macro, but using a polygonal path instead.
  808.  
  809. \vskip\myskip
  810. \noindent\macro{parafcn}[\<tmin\>,\<tmax\>,\<step\>,%
  811. (\<expr0\>,\<expr1\>)]
  812.  
  813. \nobreak
  814.  
  815. This macro plots the parametric path determined by
  816. $(x(t),y(t))=${\tt (\<expr0\>,\<expr1\>)}, where
  817. \<expr0\> and \<expr1\> are written with the only unknown
  818. being {\tt t}, using as $t$ values the points starting
  819. with \<tmin\> and stepping by \<step\> until reaching
  820. \<tmax\>.  The function is interpolated with a \MF\
  821. Bezier path.  The expressions  \<expr0\> and \<expr1\>
  822. are passed directly into the corresponding \MF\ macro, as
  823. in the \macro{function} macro, so the same operations are
  824. available.
  825.  
  826. \vskip\myskip
  827. \noindent\macro{polyparafcn}[\<tmin\>,\<tmax\>,%
  828. \<step\>,(\<expr0\>,\<expr1\>)]
  829.  
  830. \nobreak
  831. This macro plots the parametric path specified as in the
  832. \macro{parafcn} macro, but using a polygonal path instead.
  833.  
  834. \vskip\myskip
  835. \noindent\macro{shadefcn}[\<xmin\>,\<xmax\>]%
  836. [\<expr0\>][\<expr1\>]
  837.  
  838. \nobreak
  839. This macro draws the shaded region between the two
  840. functions $f(x)=$\<expr0\> and $g(x)=$\<expr1\>, where
  841. \<expr0\> and \<expr1\> are written with the only unknown
  842. being {\tt x}, bounded also by the vertical lines at
  843. \<xmin\> and \<xmax\>.  The functions $f$ and $g$ can
  844. {\it not} be allowed to cross between \<xmin\> and
  845. \<xmax\>.  The expressions  \<expr0\> and \<expr1\> are
  846. passed directly into the corresponding \MF\ macro, as in
  847. the \macro{function} macro, so the same operations are
  848. available.  The spacing between dots is determined as in
  849. the \macro{shaderect} macro; the function step size is
  850. the same distance.
  851.  
  852. \subhead{Labels and Captions.}
  853.  
  854. \vskip\myskip
  855. The next two macros do not affect the \MF\ file
  856. ({\tt\<font\>.mf}) at all, but are added to the picture
  857. by \TeX.  Therefore, if these macros are changed or added
  858. in your document, there is no need to repeat either of
  859. the last two steps (processing with \MF\ or reprocessing
  860. with \TeX) in order to complete your \TeX\ document.
  861.  
  862. \vskip\myskip
  863. \noindent\macro{mflabel}[?\<orient\>][\<x\>][\<y\>]%
  864. [\<label text\>]
  865.  
  866. \nobreak
  867. This macro places a \TeX\ label on the graph.  Without
  868. the {\tt [\<orient\>]} parameter, the label is placed
  869. with the lower left-hand corner of the label at the point
  870. {\tt (\<x\>,\<y\>)}.
  871. Note the different format of the
  872. point specification from the other {\tt mfpic} macros ---
  873. this is because \macro{mflabel} does not use \MF\ to place
  874. the label, but instead uses \TeX\ \macro{kern} commands.
  875. The optional parameter {\tt [\<orient\>]} specifies the
  876. relative placement of the label with respect to the point
  877. {\tt (\<x\>,\<y\>)} --- \<orient\> is a two-character
  878. sequence where the first character is one of {\tt t}
  879. (top), {\tt c} (center), or {\tt b} (bottom), to specify
  880. vertical placement, and the second character is one of
  881. {tt l} (left), {\tt c} (center), or {\tt r} (right), to
  882. specify horizontal placement.  The default orientation is
  883. equivalent to specifying {\tt [bl]}.
  884. The macro \macro{label} has been let equal to \macro{mflabel} for
  885. backward compatibility with version {\tt 0.2}.
  886.  
  887. \vskip\myskip
  888. \noindent\macro{mfcaption}[\<caption text\>]
  889.  
  890. \nobreak
  891. This macro places a caption at the bottom of the graph.
  892. The caption text can also include the macro
  893. {\tt\string\\}, which forces a line break in the caption.
  894. The macro \macro{caption} has been let equal to \macro{mfcaption}
  895. for backward compatibility.
  896.  
  897. \subhead{For Power Users Only.}
  898.  
  899. \vskip\myskip
  900. \noindent\macro{mfcmd}[\<command text\>]
  901.  
  902. \nobreak
  903. This macro writes the \<command text\> directly to the
  904. Metafont file, using a \TeX\ \macro{write} command.  This
  905. can have some rather bizarre consequences, though, so
  906. using it is not recommended.
  907.  
  908. \head{Using {\tt mfpic} with \LaTeX.}
  909.  
  910. {\tt mfpic.tex} is now \LaTeX\ compatible.  Since \LaTeX{} uses
  911. {\tt picture} for {\it its} {\tt picture} environment, the name
  912. {\tt mfpicture} is now preferred for an mfpic picture:\hfil\break
  913. \hbox{}\kern 1cm
  914.     \macro{begin}[mfpicture]$\dots$\macro{end}[mfpicture]\hfil\break
  915. An abbreviation `{\tt mfpic}' is provided for `{\tt mfpicture}'.
  916. The file {\tt lamfpic.tex} remains solely for backward compatibility,
  917. and it now consists merely of the command {\tt\string\input{} mfpic}.
  918. A \LaTeX\ version of the sample file, {\tt lapictures.tex}, has
  919. also been provided.
  920. Note that the \macro{opengraphsfile} and \macro{closegraphsfile}
  921. macros have {\it not} been converted into a \LaTeX\ environment.
  922.  
  923. \head{In the \LaTeX{} {\tt center} environment.}
  924.  
  925. To center an {\tt mfpic} picture within a \LaTeX\ {\tt center}
  926. environment, go into horizontal mode after the {\tt center}.
  927. For example, using \macro{noindent}:\hfil\break
  928. \hbox{}\kern 1cm    \macro{begin}[center]\hfil\break
  929. \hbox{}\kern 1cm    \macro{noindent}\hfil\break
  930. \hbox{}\kern 1cm    \macro{begin}[mfpic]\dots\hfil\break
  931. \hbox{}\kern 1cm    \dots\hfil\break
  932. \hbox{}\kern 1cm    \macro{end}[mfpic]\hfil\break
  933. \hbox{}\kern 1cm    \macro{end}[center]\hfil\break
  934. Instead of the \TeX\ primitive \macro{noindent}, the plain \TeX\ macro
  935. \macro{leavevmode} may be used.  The drawing is positioned in the
  936. same place in both cases.
  937. Unfortunately, experiments showed that the following device:\hfil\break
  938. \hbox{}\kern 1cm    \macro{ifvmode}\hfil\break
  939. \hbox{}\kern 2cm    \macro{leavevmode}\hfil\break
  940. \hbox{}\kern 1cm    \macro{fi}\hfil\break
  941. within {\tt mfpic.tex} to accommodate a possible enclosing \LaTeX{}
  942. {\tt center} environment, creates an hbox of excessive width, and that
  943. foils the use of {\tt mfpic} in such valuable situations as placing
  944. two pictures side-by-side.  So mfpic users must deal with the \LaTeX{}
  945. {\tt center} environment by inserting \macro{noindent} or
  946. \macro{leavevmode} themselves.
  947.  
  948. \head{Acknowledgements.}
  949.  
  950. I would like to thank all of the people here at Dartmouth
  951. as well as out in the network world for testing {\tt
  952. mfpic} and sending me back comments.  I would
  953. particularly like to thank Geoffrey Tobin
  954. (ecsgrt@luxor.latrobe.edu.au) for his many suggestions,
  955. especially about cleaning up the \MF\ code, enforcing
  956. dimensions, fixing the dotted line computations, and
  957. speeding up the shading routines (through this process,
  958. Geoffrey and I managed to teach each other many of the
  959. subtleties of \MF); and Bryan Green
  960. (bgreen@sanjuan.uvic.ca) for his many suggestions, some
  961. of which (including his rewriting the \macro{mfcaption}
  962. macro) ultimately led to the current version's ability to
  963. put graphs in-line or side-by-side.
  964.  
  965. \head{Changes History.}
  966.  
  967. \noindent{\it Version 0.0.x:}  Development versions.
  968. Never released.
  969. \par\noindent{\it Version 0.1:}  First version released
  970. to network, Tue 30 June 1992.
  971. \par\noindent{\it Version 0.1.x:}  Test versions for new
  972. features, fixes, etc.
  973. None of them were released for general distribution.
  974. Many new features added, bugs
  975. worked out, code cleaned up.
  976. \par\noindent{\it Version 0.2:}  Second version released
  977. to network, Mon 7 September 1992.
  978. \par\noindent{\it Version 0.25:}  Bug fixes:  Picture TFM detection,
  979. LaTeX picture environment respected, fractional scales, @ catcode
  980. restored, sharp character for MF file, bad mflabel options detected,
  981. MF char codes out of range (0 to 255) detected.
  982.  
  983. Tue 12 October 1993.
  984.  
  985. \end
  986.  
  987.